import { Meta, Status, Props, Story } from '../../../../.storybook/components';
import * as Stories from './Body.stories';

<Meta of={Stories} />

# Body

<Status variant="stable" />

The Body component is used to present content to our users.

<Story of={Stories.Base} />
<Props />

## Usage guidelines

## Component variations

### Sizes

The Body component comes in three sizes. Use the default `m` size in most cases.

<Story of={Stories.Sizes} />

### Weights

The Body component comes in three weights. Use the default `regular` weight in most cases. Use the `as` prop to render bold text with the `strong` HTML element if appropriate.

<Story of={Stories.Weights} />

### Decorations

The Body component comes in two styles. Use the `as` prop to render the component as the `em` or `del` HTML elements if appropriate.

<Story of={Stories.Decorations} />

### Colors

The Body component accepts any foreground color token name. Use the default `normal` color in most cases.

<Story of={Stories.Colors} />

### Variants

<Status variant="deprecated" />

The Body component accepts five different variants—`highlight`, `quote`, `confirm`, `alert` and `subtle`—to tailor it according to the content we are presenting.

Different variants will render different HTML elements by default:

| Variant     | Default element |
| ----------- | --------------- |
| _default_   | `p`             |
| `highlight` | `strong`        |
| `quote`     | `blockquote`    |
| `confirm`   | `p`             |
| `alert`     | `p`             |
| `subtle`    | `p`             |

Use the `as` prop to render other HTML elements, for example for rendering a highlighted paragraph (`<Body variant="highlight" as="p" />`).

<Story of={Stories.Variants} />

**Important**: the `confirm` and `alert` variants only change the text's color. Keep in mind that this is not sufficient to make them accessible. Refer to the Accessibility section below, especially "Do not rely on color alone" and "Make status messages accessible to screen readers using live regions".

---

## Accessibility

### Best practices

#### Break text up into sections

In order to make content easier to digest (especially on content-heavy pages such as articles or landing pages), break text up into sections.

- Use semantic HTML elements and headings (use the [Headline](Typography/Headline) component) to build sections into your markup
- Add spacing between paragraphs and sections for sighted users (use the [`spacing()` style mixin](Features/Style-Mixins/Spacing))

This is beneficial to everyone, but critical for users with cognitive, language or learning disabilities (such as dyslexia or ADHD).

#### Write simple copy

Similarly to how breaking text up into sections helps users _parse_ content, writing concise and simple copy helps users _understand_ content.

- Avoid the figurative use of words, or specialized words ([3.1.3: Unusual Words](https://www.w3.org/WAI/WCAG21/Understanding/unusual-words))
- Allow users to access the expanded form of abbreviations ([3.1.4: Abbreviations](https://www.w3.org/WAI/WCAG21/Understanding/abbreviations))
- Write content as clearly and simply as possible ([3.1.5: Reading Level](https://www.w3.org/WAI/WCAG21/Understanding/reading-level))

_Note: the success criteria referenced above are intended for AAA conformance. Though they are not requirements, they are a best practice and following them will improve the accessibility of our content._

#### Complement text with images

Images, graphs, or other illustrations can help users contextualize and/or understand a piece of content.

Visuals should usually complement text—and not replace it—unless an excellent description is provided as alternative text.

#### Translate content

Translate content intended for a linguistically diverse audience, and make it easy for users to change the page's language.

Bear in mind that machine translation is often inaccurate: prefer professional translation in order to give the best possible experience to users from diverse linguistic backgrounds.

#### Do not rely on color alone

Color alone is not sufficient to differentiate text from the surrounding content ([1.4.1 Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html)).

This is especially relevant when using the `confirm` and `alert` variants.

For example, imagine a list of good and bad accessibility practices. It is not enough to use the `confirm` (green) variant for good practices and the `alert` (red) variant for bad practices. Instead, use additional visual cues such as icons (with an accessible label), or break up the list into two separate ones with explicit labeling.

#### Make status messages accessible to screen readers using live regions

When a change in content is not given focus (typically a message being added to the DOM to reflect a status update), the change needs to be announced to screen readers using a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) ([4.1.3 Status Messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html), [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG21/Understanding/error-identification)).

For example, a form submission fails and a message saying "This username is already taken." using `<Body variant="alert" />` appears. Without a live region, screen reader users would have no way of knowing that something happened and that they need to make changes to the form before submitting again. They will either have to step through the DOM to try and find the relevant error message, or they will give up and close the page.

Live regions can be tricky to work with, therefore we recommend using existing components such as the [NotificationInline](Notifications/NotificationInline) or the [NotificationToast](Notifications/NotificationToast) instead of implementing them from scratch.

### Resources

#### Visualizing document structure

Use a tool like [Wave](https://wave.webaim.org/) to extract structure from a page (in Wave, you'll find the page structure under the _Structure_ tab). Verify that your copy is accurately grouped and labeled by headings.

#### Verify your UI without color

Simulate vision deficiencies or desaturate your page, and verify that visual cues beyond color are helping users understand your copy.

- [Simulate vision deficiencies using Firefox](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector/Simulation)
- [Simulate vision deficiencies using Chrome](https://developer.chrome.com/blog/new-in-devtools-83/#vision-deficiencies)
- Desaturate a page using [Wave](https://wave.webaim.org/) (under Contrast, "Desaturate page")

#### Test your page using a screen reader

[Test your page using a screen reader](https://webaim.org/articles/screenreader_testing/) like JAWS (Windows), NVDA (Windows, Linux) or VoiceOver (macOS).

This is particularly valuable for highly dynamic content, for example using live regions.

#### Further reading

- [Writing for Web Accessibility](https://www.w3.org/WAI/tips/writing/) (w3.org)
- [Cognitive Disabilities](https://webaim.org/articles/cognitive/) (WebAIM)

#### Related WCAG success criteria

- 1.4.1: [Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html)
- 3.1.3: [Unusual Words](https://www.w3.org/WAI/WCAG21/Understanding/unusual-words) (AAA)
- 3.1.4: [Abbreviations](https://www.w3.org/WAI/WCAG21/Understanding/abbreviations) (AAA)
- 3.1.5: [Reading Level](https://www.w3.org/WAI/WCAG21/Understanding/reading-level) (AAA)
- 3.3.1: [Error Identification](https://www.w3.org/WAI/WCAG21/Understanding/error-identification)
- 4.1.3: [Status Messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html)
